home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / strg61a.arc / STRGREF.DOC < prev    next >
Text File  |  1991-01-22  |  90KB  |  1,961 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.                                  STRG UTILITIES
  20.                                  REFERENCE GUIDE
  21.  
  22.                                   Version 6.1a
  23.                                 January 23, 1991
  24.  
  25.  
  26.                Copyright (C) 1989-1991 Eagle Performance Software
  27.                               All Rights Reserved.
  28.  
  29.  
  30.  
  31.                                _______                     
  32.                           ____|__     |               (tm) 
  33.                        --|       |    |------------------- 
  34.                          |   ____|__  |  Association of    
  35.                          |  |       |_|  Shareware         
  36.                          |__|   o   |    Professionals     
  37.                        -----|   |   |--------------------- 
  38.                             |___|___|    MEMBER            
  39.  
  40.  
  41.    STRG Utilities                               Reference Guide, Version 6.1a
  42.  
  43.  
  44.  
  45.                        T A B L E   O F   C O N T E N T S
  46.  
  47.         1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 4
  48.              Purpose . . . . . . . . . . . . . . . . . . . . . . . 4
  49.              Parameters  . . . . . . . . . . . . . . . . . . . . . 4
  50.              Code Size . . . . . . . . . . . . . . . . . . . . . . 5
  51.              Speed . . . . . . . . . . . . . . . . . . . . . . . . 5
  52.  
  53.         2. PROCEDURES AND FUNCTIONS  . . . . . . . . . . . . . . . 6
  54.              AscStr  . . . . . . . . . . . . . . . . . . . . . . . 6
  55.              ChrDel* . . . . . . . . . . . . . . . . . . . . . . . 6
  56.              ChrFill . . . . . . . . . . . . . . . . . . . . . . . 7
  57.              ChrPad* . . . . . . . . . . . . . . . . . . . . . . . 7
  58.              ChrPos* . . . . . . . . . . . . . . . . . . . . . . . 7
  59.              ChrQty* . . . . . . . . . . . . . . . . . . . . . . . 8
  60.              ChrRepl*  . . . . . . . . . . . . . . . . . . . . . . 8
  61.              Copy  . . . . . . . . . . . . . . . . . . . . . . . . 9
  62.              Delete  . . . . . . . . . . . . . . . . . . . . . . . 9
  63.              Is* . . . . . . . . . . . . . . . . . . . . . . . . . 9
  64.              LnStr . . . . . . . . . . . . . . . . . . . . . . . . 10
  65.              LoCase  . . . . . . . . . . . . . . . . . . . . . . . 11
  66.              Pos . . . . . . . . . . . . . . . . . . . . . . . . . 11
  67.              StrAsc  . . . . . . . . . . . . . . . . . . . . . . . 11
  68.              StrLn . . . . . . . . . . . . . . . . . . . . . . . . 12
  69.              Str*  . . . . . . . . . . . . . . . . . . . . . . . . 12
  70.              StrBin  . . . . . . . . . . . . . . . . . . . . . . . 13
  71.              StrBrk  . . . . . . . . . . . . . . . . . . . . . . . 13
  72.              StrCat* . . . . . . . . . . . . . . . . . . . . . . . 13
  73.              StrCmp* . . . . . . . . . . . . . . . . . . . . . . . 14
  74.              StrCopy . . . . . . . . . . . . . . . . . . . . . . . 14
  75.              StrCut  . . . . . . . . . . . . . . . . . . . . . . . 15
  76.              StrDeTab  . . . . . . . . . . . . . . . . . . . . . . 15
  77.              StrEnum . . . . . . . . . . . . . . . . . . . . . . . 15
  78.              StrFill . . . . . . . . . . . . . . . . . . . . . . . 15
  79.              StrHex  . . . . . . . . . . . . . . . . . . . . . . . 16
  80.              StrIns  . . . . . . . . . . . . . . . . . . . . . . . 16
  81.              StrJ* . . . . . . . . . . . . . . . . . . . . . . . . 17
  82.              StrLwr  . . . . . . . . . . . . . . . . . . . . . . . 17
  83.              StrMemb . . . . . . . . . . . . . . . . . . . . . . . 17
  84.              StrMove . . . . . . . . . . . . . . . . . . . . . . . 18
  85.              StrOvr  . . . . . . . . . . . . . . . . . . . . . . . 18
  86.              StrPeek . . . . . . . . . . . . . . . . . . . . . . . 18
  87.              StrPoke . . . . . . . . . . . . . . . . . . . . . . . 19
  88.              StrPos* . . . . . . . . . . . . . . . . . . . . . . . 19
  89.              StrQty* . . . . . . . . . . . . . . . . . . . . . . . 19
  90.              StrRepl*  . . . . . . . . . . . . . . . . . . . . . . 20
  91.              StrReTab  . . . . . . . . . . . . . . . . . . . . . . 21
  92.              StrRev  . . . . . . . . . . . . . . . . . . . . . . . 21
  93.              StrRoll . . . . . . . . . . . . . . . . . . . . . . . 21
  94.              StrSort . . . . . . . . . . . . . . . . . . . . . . . 21
  95.              StrSpn  . . . . . . . . . . . . . . . . . . . . . . . 22
  96.              StrUpr  . . . . . . . . . . . . . . . . . . . . . . . 22
  97.              UpCase  . . . . . . . . . . . . . . . . . . . . . . . 23
  98.  
  99.  
  100.                                        2
  101.    STRG Utilities                               Reference Guide, Version 6.1a
  102.  
  103.  
  104.              ValBin  . . . . . . . . . . . . . . . . . . . . . . . 23
  105.              ValHex  . . . . . . . . . . . . . . . . . . . . . . . 23
  106.              Wrd*  . . . . . . . . . . . . . . . . . . . . . . . . 24
  107.              WrdParse  . . . . . . . . . . . . . . . . . . . . . . 24
  108.              WrdPos* . . . . . . . . . . . . . . . . . . . . . . . 25
  109.              WrdQty  . . . . . . . . . . . . . . . . . . . . . . . 26
  110.              WrdToken  . . . . . . . . . . . . . . . . . . . . . . 26
  111.  
  112.         3. VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 28
  113.              Global  . . . . . . . . . . . . . . . . . . . . . . . 28
  114.              Local . . . . . . . . . . . . . . . . . . . . . . . . 29
  115.  
  116.         4. ACCESSIBLE MEMORY . . . . . . . . . . . . . . . . . . . 30
  117.  
  118.         5. QUICK REFERENCE . . . . . . . . . . . . . . . . . . . . 31
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.                                        3
  161.    STRG Utilities                               Reference Guide, Version 6.1a
  162.  
  163.  
  164.    1.  I N T R O D U C T I O N
  165.  
  166.  
  167.    PURPOSE
  168.  
  169.    This document is a STRG technical reference manual describing each routine 
  170.    and variable in detail in a format similar to the Borland manual.  The 
  171.    routines are described in alphabetical order.  Since this manual is on 
  172.    disk, you can find your interest easily with a search utility.
  173.  
  174.    Application - All STRG procedures process strings with high-speed optimized 
  175.    assembly code.  To be as fast as possible, almost all routines are 
  176.    procedures rather than functions to increase speed 2 to 3 times.
  177.  
  178.  
  179.    PARAMETERS
  180.  
  181.    Common Parameters - Most procedures use the same parameters.  Rather than 
  182.    repeating them for each routine, detailed descriptions for those parameters 
  183.    are listed below.
  184.  
  185.      Count    - number of characters or substrings to copy.
  186.      Decimals - number of digits to the right of the decimal.
  187.      Dest     - Pascal destination string (as opposed to source).
  188.      Field    - number of digits in the field.
  189.      Find     - a character or substring to find in a source string.
  190.      Index    - the starting offset in the Pascal source string.
  191.      MaxLen   - the maximum length permitted for the resulting string to 
  192.                 prevent overwriting memory.
  193.      Nth      - process until the "Nth" occurrence.
  194.      Repl     - replacement character or substring.
  195.      S        - Pascal source string.
  196.      Source   - Pascal source string (as opposed to destination).
  197.  
  198.    Order of Parameters - Of course not all of these parameters may be used, 
  199.    but the order of the parameters is consistent throughout the routines.  
  200.    Here is the general order:
  201.  
  202.      1. Destination - such as Dest
  203.      2. Source      - such as S and Source
  204.      3. Substrings  - such as Find, Repl, Fill, First, and Last
  205.      4. Index       - always of the source
  206.      5. Count       - such as Count, Field, Nth and Qty
  207.      6. Maximum     - maximum length of destination string 
  208.  
  209.    This arrangement matches that of C.  For procedures, if there is a 
  210.    destination, it is always the first parameter; just like the assignment, 
  211.    (":=") the destination is always on the left.
  212.  
  213.    Index - All index parameters are 1-based.  If a zero is entered, it is 
  214.    converted to 1.  The Delete procedure is the only exception to this, but it 
  215.    is part of standard Pascal.
  216.  
  217.  
  218.  
  219.  
  220.    Chapter 1, Introduction                                             Page 4
  221.    STRG Utilities                               Reference Guide, Version 6.1a
  222.  
  223.  
  224.    CODE SIZE
  225.  
  226.    Unit Size - If you use a STRG procedure, only the corresponding object file 
  227.    containing that procedure will be linked and thereby optimizing the code.  
  228. |  Even if all 111 procedures are used, STRG is still quite small at a total 
  229. |  of about 6.3k bytes.  In all, there are 78 object files used to create the 
  230. |  unit which is about 5900 lines of assembly or 250k of code.
  231.  
  232.    Code Usage - This Shareware unit has been released with the $N+ and $E+ 
  233.    compiler directives set.  This means that an additional 12k of code is 
  234.    included for the IEEE reals library inserted by the compiler.  The IEEE 
  235.    reals are used in the Str* numeric formatting functions and are enabled for 
  236.    your testing.  Should you not want to use these functions and are a 
  237.    registered user, you can turn off these directives at the beginning of the 
  238.    STRG unit.  This will drop the IEEE library from the executable code.
  239.  
  240.  
  241.    SPEED
  242.  
  243.    Speed Bench - How fast is fast?  To have a basis for comparison, a unit of 
  244.    strings-per-second (str/sec) is used for a relative measure of speed.  To 
  245.    get this rating, a routine is repeated with a FOR loop to operate on a 
  246.    given string and any "reset" of the original string is subtracted out as 
  247.    overhead.  The RATE61.PAS program can duplicate this for you so you can 
  248.    bench test your own routines for actual speed.  Overall, if you use STRG 
  249.    for your application, your speeds will easily be 3 times faster or more.
  250.  
  251.    Relative Speed - The ratings mentioned in the Reference Manual are speeds 
  252.    obtained from actual bench test on an 80386 / 20 MHz machine.  Granted, 
  253.    that this may be faster than most units, but the important aspect of these 
  254.    ratings is relative speed.  By comparing ratings with other routines in 
  255.    this unit, you can judge how to best assemble a program technique that can 
  256.    suit your needs.
  257.  
  258.    Processing Rating - Not only can machines vary in speed, but the string 
  259.    values in your program are complete variables.  When given a routine like 
  260.    StrPosL, the test performed is on an 80-character string with a 5-letter 
  261.    word at the end of the string.  So the test forces the routine to search 
  262.    the entire string.  This provides a worst case scenario to give you a feel 
  263.    for the length of time for an operation.  Similarly, StrPosR is tested with 
  264.    the 5-letter word at the beginning of the string and so the ratings for 
  265.    both routines are about the same.  But one of these routines may be much 
  266.    better for your program from a strategic standpoint.  So, the rating 
  267.    provided gives one of processing performance and not from the perspective 
  268.    that a better rating means faster speed for your application.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.    Chapter 1, Introduction                                             Page 5
  281.    STRG Utilities                               Reference Guide, Version 6.1a
  282.  
  283.  
  284.    2.  P R O C E D U R E S   A N D   F U N C T I O N S
  285.  
  286.    In this section, a detailed description is provided for each procedure and 
  287.    function.
  288.  
  289.  
  290.    ---------------------------------------------------------------------------
  291.    AscStr procedure                                                       Strg
  292.    ---------------------------------------------------------------------------
  293.    Function       Creates ASCIIZ strings from Pascal-type strings.
  294.    Declaration    AscStr (VAR AscDest; S: string)
  295.    Remarks        After AscStr is executed, the global variable AscDestPtr is 
  296.                   updated to point to the next destination address just after 
  297.                   the null.  Source and destination can be the same.  As in 
  298.                   all move-type procedures, it is important to make sure the 
  299.                   destination size is sufficient to fit the source.
  300.    Rating         42,900 str/sec
  301.    See also       LnStr, StrAsc and the variable AscDestPtr.
  302.    Example        Pack three Pascal strings into an array of ASCIIZ strings.
  303.  
  304.                     uses strg;
  305.                     var
  306.                       S: array[0..4] of string;
  307.                       A: array[0..26] of char;
  308.                       i: byte;
  309.                     begin
  310.                       S[1] := 'Eagle';
  311.                       S[2] := 'Performance';
  312.                       S[3] := 'Software';
  313.                       AscDestPtr := @A;
  314.                       for i:=1 to 3 do
  315.                         AscStr (AscDestPtr^,S[i]);
  316.                     end.
  317.  
  318.                   The resulting array A would look like:
  319.  
  320.                     'Eagle'#00'Performance'#00'Software'#00
  321.  
  322.    ---------------------------------------------------------------------------
  323.    ChrDel* procedure                                                      Strg
  324.    ---------------------------------------------------------------------------
  325.    Function       Operates on a string to delete a given character.
  326.    Declaration    ChrDel  (VAR S: string; Find: char)
  327.                   ChrDelL (VAR S: string; Find: char)
  328.                   ChrDelR (VAR S: string; Find: char)
  329.    Remarks        ChrDel deletes all finds in the entire string.
  330.                   ChrDelL deletes only left (or leading) finds.
  331.                   ChrDelR deletes only right (or trailing) finds.
  332.    Rating         ChrDel:    9,400 str/sec
  333.                   ChrDelL:  39,000 str/sec
  334.                   ChrDelR: 132,000 str/sec
  335.    See also       StrCut
  336.    Example        Try these examples:
  337.  
  338.  
  339.  
  340.    Chapter 2, Procedures and Functions                                 Page 6
  341.    STRG Utilities                               Reference Guide, Version 6.1a
  342.  
  343.  
  344.                     MyString := '   more info ';
  345.                     MyNumStr := '1,234,567';
  346.                     ChrDel  (MyNumStr,',');    { MyNumStr='1234567'      }
  347.                     ChrDelL (MyString,' ');    { MyString='more info '   }
  348.                     ChrDelR (MyString,' ');    { MyString='   more info' }
  349.  
  350.    ---------------------------------------------------------------------------
  351.    ChrFill procedure                                                      Strg
  352.    ---------------------------------------------------------------------------
  353.    Function       Fills a string with multiple copies of a character.
  354.    Declaration    ChrFill (VAR S: string; Fill: char; Count: byte)
  355.    Remarks        The fill overwrites S with Count number of repetitions of 
  356.                   Fill and automatically sets the length byte.  Be sure the 
  357.                   destination is large enough.  Up to twice as fast as using 
  358.                   system.fillchar.
  359.    Rating         53,400 str/sec
  360.    See also       StrEnum, StrFill
  361.    Example        Try the following example:
  362.  
  363.                     ChrFill (S,'a',5);    { S='aaaaa' }
  364.  
  365.    ---------------------------------------------------------------------------
  366.    ChrPad* procedure                                                      Strg
  367.    ---------------------------------------------------------------------------
  368.    Function       Pads a string on the left, right, or to center with a given 
  369.                   character to fill a field.
  370.    Declaration    ChrPadC (VAR S: string; Fill: char; Field: byte)
  371.                   ChrPadL (VAR S: string; Fill: char; Field: byte)
  372.                   ChrPadR (VAR S: string; Fill: char; Field: byte)
  373.    Remarks        ChrPadC pads left and right to center the field.
  374.                   ChrPadL pads on the left (or leading) fill.
  375.                   ChrPadR pads on the right (or trailing) fill.
  376.    Rating         ChrPadC: 36,500 str/sec
  377.                   ChrPadL: 42,900 str/sec
  378.                   ChrPadR: 52,000 str/sec
  379.    See also       ChrDel, StrCut, StrJ*
  380.    Example        Try these examples:
  381.  
  382.                     MyStr := 'abcdefgh';       {        12345678901   }
  383.                     ChrPadC (MyStr,'*',11);    { MyStr='*abcdefgh**'  }
  384.                     ChrPadL (MyStr,'=',11);    { MyStr='===abcdefgh'  }
  385.                     ChrPadR (MyStr,' ',11);    { MyStr='abcdefgh   '  }
  386.  
  387.    ---------------------------------------------------------------------------
  388.    ChrPos* function                                                       Strg
  389.    ---------------------------------------------------------------------------
  390.    Function       Finds the position of a given character with match/ignore 
  391.                   case.
  392.    Declaration    ChrPosL  (S: string; Find: char; Nth: byte)
  393.                   ChrPosLI (S: string; Find: char; Nth: byte)
  394.                   ChrPosR  (S: string; Find: char; Nth: byte)
  395.                   ChrPosRI (S: string; Find: char; Nth: byte)
  396.                   ChrPosX  (S: string; Find: char; indeX: byte)
  397.                   ChrPosXI (S: string; Find: char; indeX: byte)
  398.  
  399.  
  400.    Chapter 2, Procedures and Functions                                 Page 7
  401.    STRG Utilities                               Reference Guide, Version 6.1a
  402.  
  403.  
  404.    Result type    byte
  405.    Remarks        Using suffixes, -L routine searches from the left while the 
  406.                   -R searches from the right for the Nth occurrence.  The -X 
  407.                   routine starts at the given index and searches right for the 
  408.                   first occurrence.  These routines match case, while those 
  409.                   with the added -I suffix will Ignore case.
  410.    Rating         ChrPos?:  25,400 str/sec
  411.                   ChrPos?I: 22,500 str/sec  (non-alphabetic Find)
  412.                   ChrPos?I: 10,200 str/sec  (alphabetic Find)
  413.    See also       StrBrk, StrPos*
  414.    Example        Try the following examples:
  415.  
  416.                     S1 := 'C:\MySubDir\SubDir#2\myfile';
  417.                     S2 := 'Eagle Performance Software';
  418.                     MyByte := ChrPosR  (S1,'\',1);   { MyByte=21 }
  419.                     MyByte := ChrPosLI (S2,'e',3);   { MyByte= 8 }
  420.                     MyByte := ChrPosXI (S2,'s',8);   { MyByte=19 }
  421.  
  422.    ---------------------------------------------------------------------------
  423.    ChrQty* function                                                       Strg
  424.    ---------------------------------------------------------------------------
  425.    Function       Counts the occurrences of a given character in 
  426.                   a string with match/ignore case.
  427.    Declaration    ChrQty  (S: string; Find: char)
  428.                   ChrQtyI (S: string; Find: char)
  429.    Result type    byte
  430.    Remarks        ChrQty matches case while ChrQtyI ignores case.
  431.    Rating         ChrQty:  23,100 str/sec
  432.                   ChrQtyI: 22,500 str/sec  (non-alphabetic Find)
  433.                   ChrQtyI: 10,200 str/sec  (alphabetic Find)
  434.    See also       StrQty*, WrdQty
  435.    Example        Given a string, S:='Eagle Performance Software', try the 
  436.                   following examples:
  437.  
  438.                     MyByte := ChrQty  (S,'a');   { MyByte=3 }
  439.                     MyByte := ChrQtyI (S,'e');   { MyByte=5 }
  440.  
  441.    ---------------------------------------------------------------------------
  442.    ChrRepl* procedure                                                     Strg
  443.    ---------------------------------------------------------------------------
  444.    Function       Finds and replaces a character from a given index for Qty 
  445.                   number of replacements with match/ignore case. 
  446.    Declaration    ChrRepl  (VAR S: string; Find,Repl: char; Index,Qty: byte)
  447.                   ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte)
  448.    Remarks        The operation starts from Index and goes to the right.  It 
  449.                   will stop if the index is beyond the end of string or it has 
  450.                   replaced as many as it can.  ChrRepl matches case while 
  451.                   ChrReplI ignores case.
  452.    Rating         ChrRepl:  21,300 str/sec
  453.                   ChrReplI: 20,300 str/sec  (non-alphabetic Find)
  454.                   ChrReplI: 10,000 str/sec  (alphabetic Find)
  455.    See also       ChrDel*, StrRepl*
  456.    Example        Try the following example:
  457.  
  458.  
  459.  
  460.    Chapter 2, Procedures and Functions                                 Page 8
  461.    STRG Utilities                               Reference Guide, Version 6.1a
  462.  
  463.  
  464.                     S := '/s -12 -cga /off';
  465.                     ChrRepl (S,'-','/',1,255);   { S='/s /12 /cga /off' }
  466.  
  467.    ---------------------------------------------------------------------------
  468.    Copy function                                                          Strg
  469.    ---------------------------------------------------------------------------
  470.    Function       Returns a substring of a string.
  471.    Declaration    Copy (S: string; Index,Count: integer)
  472.    Result type    string
  473.    Remarks        Exact replacement of the System.Copy function, but 
  474.                   automatically replaces it with one that is up to 34% faster.
  475.    Rating         21,500 str/sec
  476.    See also       StrCopy, StrOvr, Compiler reference manual
  477.  
  478.    ---------------------------------------------------------------------------
  479.    Delete procedure                                                       Strg
  480.    ---------------------------------------------------------------------------
  481.    Function       Deletes a substring from a string.
  482.    Declaration    Delete (VAR S: string; Index,Count: integer)
  483.    Remarks        Exact replacement of the System.Delete procedure, but 
  484.                   automatically replaces it with one that is up to 5 times 
  485.                   faster.
  486.    Rating         39,300 str/sec
  487.    See also       ChrDel*, StrCut, Compiler reference manual
  488.  
  489.    ---------------------------------------------------------------------------
  490.    Is* function                                                           Strg
  491.    ---------------------------------------------------------------------------
  492.    Function       Character classification function.
  493.    Declaration    IsAlNum  (C: char)   { Alpha-numeric }
  494.                   IsAlpha  (C: char)   { Upper and lower case letters }
  495.                   IsASCII  (C: char)   { Lower ASCII table }
  496.                   IsCntrl  (C: char)   { Print control characters }
  497.                   IsDigit  (C: char)   { 0 through 9 }
  498.                   IsDOS    (C: char)   { Valid DOS directory & wildcards }
  499.                   IsFile   (C: char)   { Valid DOS file name }
  500.                   IsGraph  (C: char)   { Black characters }
  501.                   IsLower  (C: char)   { Lower case letters }
  502.                   IsPath   (C: char)   { Valid DOS path & drive & subdirs }
  503.                   IsPrint  (C: char)   { Printable characters }
  504.                   IsPunct  (C: char)   { Punctuation marks }
  505.                   IsReal   (C: char)   { Real numbers }
  506.                   IsSigned (C: char)   { Signed integers }
  507.                   IsSpace  (C: char)   { Space or line control }
  508.                   IsUpper  (C: char)   { Upper case letters }
  509.                   IsXDigit (C: char)   { Hex digits }
  510.    Result type    boolean
  511.    Remarks        These exactly duplicate the C implementation of character 
  512.                   classification, but a few are unique to STRG.  The best 
  513.                   balance of speed and code is used for each one and they are 
  514.                   more efficient than the use of sets.  All functions only 
  515.                   consider characters in the lower ASCII table (<#128).  The 
  516.                   function will return TRUE if the following characters are 
  517.                   passed (the "-" means through):
  518.  
  519.  
  520.    Chapter 2, Procedures and Functions                                 Page 9
  521.    STRG Utilities                               Reference Guide, Version 6.1a
  522.  
  523.  
  524.  
  525.                     IsAlNum:   0-9 A-Z a-z
  526.                     IsAlpha:   A-Z a-z
  527.                     IsASCII:   Less than #128
  528.                     IsCntrl:   #00-#31 #127
  529.                     IsDigit:   0-9
  530.                     IsDOS:     ! #-* #45 #46 0-: ?-Z \ ^-{ }-~
  531.                     IsFile:    ! #-) #45 #46 0-9 @-Z   ^-{ }-~
  532.                     IsGraph:   #33-#126
  533.                     IsLower:   a-z
  534.                     IsPath:    ! #-) #45 #46 0-: @-Z \ ^-{ }-~
  535.                     IsPrint:   #32-#126
  536.                     IsPunct:   IsGraph but not IsAlNum
  537.                     IsReal:    0-9 + Minus . e E
  538.                     IsSigned:  0-9 + Minus
  539.                     IsSpace:   Space #09-#13
  540.                     IsUpper:   A-Z
  541.                     IsXDigit:  0-9 A-F a-f
  542.  
  543.                   IsDos checks for characters that are valid when asking for a 
  544.                   directory at the DOS command prompt such as:
  545.  
  546.                      C:\MySubDir\Subdir#2\All?.*
  547.  
  548.                   IsPath is the same as IsDos except it doesn't accept the 
  549.                   wildcards '*' and '?'.  IsFile is the the same as IsPath 
  550.                   except it will not accept the drive and path characters ':' 
  551.                   and '\'.
  552.    See also       StrMemb
  553.    Example        Create a membership string containing only valid Real number 
  554.                   characters:
  555.  
  556.                     S := '';
  557.                     for MyChar:='+' to 'e' do
  558.                       if IsReal (MyChar) then
  559.                         StrCat (S,MyChar,255);     { S='+-.1234567890Ee' }
  560.  
  561.    ---------------------------------------------------------------------------
  562.    LnStr procedure                                                        Strg
  563.    ---------------------------------------------------------------------------
  564.    Function       Creates ASCII TEXT strings from Pascal-type strings.
  565.    Declaration    LnStr (VAR LnDest; S: string)
  566.    Remarks        LnStr copies the characters of string S to the line 
  567.                   destination Ln and terminates the line with a CR/LF 
  568.                   (#13/#10).  After StrLn is executed, the global variable 
  569.                   LnDestPtr points to the next destination after the CR/LF.  
  570.                   As in all move-type procedures, it is important to make sure 
  571.                   the destination size is sufficient to fit the source.
  572.    Suggestions    The use of WriteLn for text files is disk intensive.  LnStr 
  573.                   can be used together with BlockWrite for extremely fast text 
  574.                   file operations.
  575.    Rating         42,200 str/sec
  576.    See also       AscStr, StrLn, and variable LnDestPtr
  577.    Example        Similar to the example in StrAsc.
  578.  
  579.  
  580.    Chapter 2, Procedures and Functions                                 Page 10
  581.    STRG Utilities                               Reference Guide, Version 6.1a
  582.  
  583.  
  584.  
  585.    ---------------------------------------------------------------------------
  586.    LoCase function                                                        Strg
  587.    ---------------------------------------------------------------------------
  588.    Function       Converts characters to lower case.
  589.    Declaration    LoCase (C: char)
  590.    Result type    char
  591.    Remarks        As the complement of UpCase, this routine converts 
  592.                   characters in the range A..Z to lower case.
  593.    See also       ChrReplI, StrLwr, StrUpr, UpCase
  594.  
  595.    ---------------------------------------------------------------------------
  596.    Pos function                                                           Strg
  597.    ---------------------------------------------------------------------------
  598.    Function       Finds the position of a substring in a string.
  599.    Declaration    Pos (Find,S: string)
  600.    Result type    integer
  601.    Remarks        Exact replacement of the System.Pos procedure, but 
  602.                   automatically replaces it with one that is up to 340% 
  603.                   faster.
  604.    Rating         24,100 str/sec
  605.    See also       ChrPos*, StrBrk, StrPos*, Compiler reference manual.
  606.  
  607.    ---------------------------------------------------------------------------
  608.    StrAsc procedure                                                       Strg
  609.    ---------------------------------------------------------------------------
  610.    Function       Creates Pascal strings from ASCIIZ-type strings.
  611.    Declaration    StrAsc (VAR Dest: string; VAR AscSrc; MaxLen: byte)
  612.    Remarks        After StrAsc is executed, the global variable AscSrcPtr 
  613.                   points to the next ASCIIZ string skipping over any null 
  614.                   character.  Should the conversion be truncated with MaxLen, 
  615.                   StrAsc makes sure that AscSrcPtr points to the next string 
  616.                   and not a null.  Source and destination can be the same.  As 
  617.                   in all move-type procedures, it is important to make sure 
  618.                   the destination size is sufficient to fit the source.
  619.    Rating         17,000 str/sec
  620.    See also       StrLn, AscStr
  621.    Example        Disassemble a sequential array of ASCIIZ strings into three 
  622.                   Pascal strings:
  623.  
  624.                     uses strg;
  625.                     const
  626.                       A: array[0..26] of char = 
  627.                          'Eagle'#00'Performance'#00'Software'#00;
  628.                     var
  629.                       S: array[0..4] of string;
  630.                       i: byte;
  631.                     begin
  632.                       AscSrcPtr := @A;
  633.                       for i:=1 to 3 do
  634.                         StrAsc (S[i],AscSrcPtr^,255);
  635.                     end.
  636.  
  637.                   The resulting strings would look like:
  638.  
  639.  
  640.    Chapter 2, Procedures and Functions                                 Page 11
  641.    STRG Utilities                               Reference Guide, Version 6.1a
  642.  
  643.  
  644.  
  645.                     S[1] := 'Eagle';
  646.                     S[2] := 'Performance';
  647.                     S[3] := 'Software';
  648.  
  649.    ---------------------------------------------------------------------------
  650.    StrLn procedure                                                        Strg
  651.    ---------------------------------------------------------------------------
  652.    Function       Creates Pascal strings from ASCII TEXT strings.
  653.    Declaration    StrLn (VAR Dest: string; VAR LnSrc; MaxLen: byte)
  654.    Remarks        ASCII text file lines by definition end with a CR (#13) or a 
  655.                   CR/LF (#13/#10).  StrLn searches for the CR and copies the 
  656.                   string prior to that character.  After StrLn is executed, 
  657.                   the global variable LnSrcPtr points to the next line 
  658.                   skipping over any CR or LF even if the string is truncated 
  659.                   with MaxLen.  Source and destination can be the same for 
  660.                   non-sequential conversions.  As in all move-type procedures, 
  661.                   it is important to make sure the destination size is 
  662.                   sufficient to fit the source.
  663.    Suggestions    The use of ReadLn for text files is disk intensive.  StrLn 
  664.                   can be used together with BlockRead for extremely fast text 
  665.                   file operations.
  666.    Rating         16,800 str/sec
  667.    See also       AscStr, LnStr, and variable LnSrcPtr
  668.    Example        Similar to the example in AscStr. 
  669.  
  670.    ---------------------------------------------------------------------------
  671.    Str* function                                                          Strg
  672.    ---------------------------------------------------------------------------
  673.    Function       Converts numbers to a string representation.
  674.    Declaration    StrC   (C: comp):
  675.                   StrCF  (C: comp; Field: integer)
  676.                   StrCFD (C: comp; Field,Decimals: integer)
  677.                   StrD   (D: double)
  678.                   StrDF  (D: double; Field: integer)
  679.                   StrDFD (D: double; Field,Decimals: integer)
  680.                   StrE   (E: extended)
  681.                   StrEF  (E: extended; Field: integer)
  682.                   StrEFD (E: extended; Field,Decimals: integer)
  683.                   StrL   (L: longint)
  684.                   StrLF  (L: longint; Field: integer)
  685.                   StrR   (R: real)
  686.                   StrRF  (R: real; Field: integer)
  687.                   StrRFD (R: real; Field,Decimals: integer)
  688.                   StrS   (S: single)
  689.                   StrSF  (S: single; Field: integer)
  690.                   StrSFD (S: single; Field,Decimals: integer)
  691.    Result type    string
  692.    Remarks        These functions use the System.Str procedure, but have been 
  693.                   converted to a function form for convenience.  Although they 
  694.                   are a fraction slower, they save code in the long run.  The 
  695.                   IEEE reals are included only if the N/E compiler directives 
  696.                   are appropriately set for your use.
  697.    Rating         Varies: uses System.Str.
  698.  
  699.  
  700.    Chapter 2, Procedures and Functions                                 Page 12
  701.    STRG Utilities                               Reference Guide, Version 6.1a
  702.  
  703.  
  704.    See also       StrBin, StrHex
  705.  
  706.    ---------------------------------------------------------------------------
  707.    StrBin function                                                        Strg
  708.    ---------------------------------------------------------------------------
  709.    Function       Converts numbers to binary strings.
  710.    Declaration    StrBin (Num: longint; Field: byte)
  711.    Result type    string
  712.    Remarks        If the field is larger than the resulting string, the field 
  713.                   is balanced with leading zeros.  If no leading zeros are 
  714.                   desired, set Field to 0.  Maximum field is 32.
  715.    Rating         13,300 str/sec
  716.    See also       StrHex, ValBin, ValHex
  717.    Example        In the following examples, the results will be String1=
  718.                   '0000111111' and String2='111111'.
  719.  
  720.                     MyByte  := 63;
  721.                     String1 := StrBin (MyByte,10);
  722.                     String2 := StrBin (MyByte,3);
  723.  
  724.    ---------------------------------------------------------------------------
  725.    StrBrk function                                                        Strg
  726.    ---------------------------------------------------------------------------
  727.    Function       Finds first character that is a member of a group of chars.
  728.    Declaration    StrBrk (S,Breaks: string; Index: byte)
  729.    Result type    byte
  730.    Remarks        Breaks (Brk) is a group of characters.  The function returns 
  731.                   the index of the first character found to be a member of 
  732.                   Breaks moving RIGHT from the given index.  Routine has fully 
  733.                   scanned when resulting index is zero.  This routine is 
  734.                   usually used to parse a string.  For greater speed, place 
  735.                   the most commonly used members early in Breaks.
  736.    Rating         1-char Breaks: 23,700 str/sec
  737.                   5-char Breaks:  5,400 str/sec
  738.    See also       ChrPos*, StrMemb, StrPosX, StrSpn
  739.    Example        Find the position of the number in the string S:
  740.  
  741.                     var 
  742.                       S,Numbers: string;
  743.                       Position: byte;
  744.                     begin
  745.                       S := 'Balance $24567.00';
  746.                       StrEnum (Numbers,'0','9');
  747.                       Position := StrBrk (S,Numbers,1);  { Position=10 }
  748.                     end.
  749.  
  750.    ---------------------------------------------------------------------------
  751.    StrCat* procedure                                                      Strg
  752.    ---------------------------------------------------------------------------
  753.    Function       Appends one string or substring to the end of another.
  754.    Declaration    StrCat  (VAR Dest: string; S: string; MaxLen: byte)
  755.                   StrCatX (VAR Dest: string; S: string; 
  756.                            indeX,Count,MaxLen: byte)
  757.    Remarks        This procedure appends the end of string Dest with S for a 
  758.  
  759.  
  760.    Chapter 2, Procedures and Functions                                 Page 13
  761.    STRG Utilities                               Reference Guide, Version 6.1a
  762.  
  763.  
  764.                   maximum length limit of MaxLen.  StrCat concatenates a full 
  765.                   string while StrCatX does a substring.  This greatly speeds 
  766.                   up concatenation.  Usually the SizeOf function is used for 
  767.                   MaxLen, or 255 can be used if there is no concern.  Like 
  768.                   Concat, but up to 5 times faster.
  769.    Rating         44,100 str/sec
  770.    See also       StrCopy, StrMove, StrOvr
  771.    Example        Given S1='Eagle ' and S2='Performance', try the following:
  772.  
  773.                     StrCatX (S1,S2,7,3,255);   ( S1='Eagle man'         }
  774.                     StrCut  (S1,6);            { S1='Eagle '            }
  775.                     StrCat  (S1,S2,255);       { S1='Eagle Performance' }
  776.  
  777.    ---------------------------------------------------------------------------
  778.    StrCmp* function                                                       Strg
  779.    ---------------------------------------------------------------------------
  780.    Function       Compares one substring to another.
  781.    Declaration    StrCmp  (S1,S2: string; Index1,Index2,MaxLen: byte)
  782.                   StrCmpI (S1,S2: string; Index1,Index2,MaxLen: byte)
  783.    Result type    shortint
  784.    Result value   After comparison, here are the possible values:
  785.                     -1:  S1<S2
  786.                      0:  S1=S2
  787.                     +1:  S1>S2
  788.    Remarks        This routine compares (Cmp) two strings and determines Less 
  789.                   Than, Equal, or Greater Than.  The comparison is made 
  790.                   between the resulting substrings starting at each 
  791.                   corresponding index and moving to the right.  The indexes 
  792.                   are not adjusted should they extend beyond the end of string 
  793.                   at which the substring is considered null.  The indexes of 
  794.                   difference are saved in the global variables CmpIndex1 and 
  795.                   CmpIndex2 which are 0 if the two substrings are equal.  
  796.                   StrCmp matches case while StrCmpI ignores case.
  797.    Rating         StrCmp:  27,800 str/sec
  798.                   StrCmpI:  4,600 str/sec
  799.    Example        The following comparison of dates yields -1, CmpIndex1=13 
  800.                   and CmpIndex2=19.
  801.  
  802.                     S1 := 'MyEvent 90-04-23';
  803.                     S2 := 'Second event: 90-05-17';
  804.                     MyShortInt := StrCmp (S1,S2,9,15,8);
  805.  
  806.    ---------------------------------------------------------------------------
  807.    StrCopy procedure                                                      Strg
  808.    ---------------------------------------------------------------------------
  809.    Function       Directly copies a substring to create a new string.
  810.    Declaration    StrCopy (VAR Dest: string; S: string; Index,Count: byte)
  811.    Remarks        This is a move procedure for strings.  Being a procedure 
  812.                   rather than a function, it is up to 3.3 times faster than 
  813.                   System.Copy.  But be sure the Dest is large enough.
  814.    Rating         47,000 str/sec
  815.    See also       Copy, StrCat, StrOvr
  816.    Example        The following example extracts the substring 'target'.
  817.  
  818.  
  819.  
  820.    Chapter 2, Procedures and Functions                                 Page 14
  821.    STRG Utilities                               Reference Guide, Version 6.1a
  822.  
  823.  
  824.                     S1 := 'This is the target word';
  825.                     StrCopy (S2,S1,13,6);           { S2='target' }
  826.  
  827.    ---------------------------------------------------------------------------
  828.    StrCut procedure                                                       Strg
  829.    ---------------------------------------------------------------------------
  830.    Function       Truncates a string above a maximum size.
  831.    Declaration    StrCut (VAR S: string; MaxLen: byte)
  832.    Rating         430,000 str/sec
  833.    See also       ChrDel*
  834.    Example        Try the following code:
  835.  
  836.                     S := 'Eagle Performance Software';
  837.                     StrCut (S,17);     { S='Eagle Performance' }
  838.  
  839.    ---------------------------------------------------------------------------
  840.    StrDeTab procedure                                                     Strg
  841.    ---------------------------------------------------------------------------
  842.    Function       Expands all tabs to spaces at a given tab spacing.
  843.    Declaration    StrDeTab (VAR Dest: string; S: string; TabSpaces: byte)
  844.    Remarks        This routine expands all tabs to spaces given the tab 
  845.                   spacing.  Source and Dest can be the same address.  Position 
  846.                   1 is the first tab setting.  Be sure Dest can handle the 
  847.                   expansion.  Strings are truncated at 255.
  848.    Rating         7,700 str/sec
  849.    See also       StrReTab
  850.    Example        Expand the tabs (#9) in the following string:
  851.  
  852.                     S := #9'Col 9'#9'Col 17';
  853.                     StrReTab (S,S,8);         { S='        Col 9   Col 17' }
  854.                                               {    1234567890123456789012  }
  855.  
  856.    ---------------------------------------------------------------------------
  857.    StrEnum procedure                                                      Strg
  858.    ---------------------------------------------------------------------------
  859.    Function       Enumerates a string of characters from First to Last.
  860.    Declaration    StrEnum (VAR S: string; First,Last: char)
  861.    Remarks        Enumeration can be increasing or decreasing, but do not wrap 
  862.                   through #00.  Be sure the destination is large enough.  
  863.                   Strings are truncated at 255.
  864.    Rating         13,300 str/sec
  865.    See also       StrFill, StrRev, StrSort
  866.    Example        Try the following examples:
  867.  
  868.                      StrEnum (S,'a','f');   { S='abcdeg' }
  869.                      StrEnum (T,'f','a');   { T='fedcba' }
  870.  
  871.    ---------------------------------------------------------------------------
  872.    StrFill procedure                                                      Strg
  873.    ---------------------------------------------------------------------------
  874.    Function       Fills a string with multiple copies of a substring.
  875.    Declaration    StrFill (VAR S: string; Fill: string; Count,MaxLen: byte)
  876.    Remarks        The fill overwrites S with concatenated copies of Fill.  A 
  877.                   special option is built in for single character fills to be 
  878.  
  879.  
  880.    Chapter 2, Procedures and Functions                                 Page 15
  881.    STRG Utilities                               Reference Guide, Version 6.1a
  882.  
  883.  
  884.                   extremely fast.  Source and destination can be the same. 
  885.                   Strings are truncated by MaxLen.
  886.    Rating         1-char fill: 44,400 str/sec
  887.                   5-char fill: 13,300 str/sec
  888.    See also       ChrFill, StrEnum
  889.    Example        Try the following examples:
  890.  
  891.                     StrFill (S,'a',5,255);    { S='aaaaa' }
  892.                     StrFill (T,'Fast',3,11);  { T='FastFastFas' }
  893.  
  894.    ---------------------------------------------------------------------------
  895.    StrHex procedure                                                       Strg
  896.    ---------------------------------------------------------------------------
  897.    Function       Converts numbers to hex strings.
  898.    Declaration    StrHex (Num: longint; Field: byte)
  899.    Remarks        If the field is larger than the resulting string, the 
  900.                   field is balanced with leading zeros.  If no leading zeros 
  901.                   are desired, set Field to 0.  Maximum field is 8.  No 
  902.                   leading '$' character is inserted.
  903.    Rating         25,100 str/sec
  904.    See also       StrBin, ValBin, ValHex
  905.    Example        Try the following examples:
  906.  
  907.                     MyWord  := 4095;
  908.                     String1 := StrHex (MyWord,5);   { String1='00FFF'    }
  909.                     String2 := StrHex (MyWord,1);   { String2='FFF'      }
  910.                     String3 := StrHex (MyWord,15);  { String3='00000FFF' }
  911.  
  912.    ---------------------------------------------------------------------------
  913.    StrIns procedure                                                       Strg
  914.    ---------------------------------------------------------------------------
  915.    Function       Inserts a substring at a given index.
  916.    Declaration    StrIns (VAR Dest: string; S: string; DestIndex,MaxLen: byte)
  917.    Remarks        The routine is processed as if the insertion was done and 
  918.                   the resulting string truncated after MaxLen.  DestIndex is 
  919.                   adjusted to the minimum of DestIndex and Dest[0].  The 
  920.                   operation is skipped if MaxLen<DestIndex or S[0]=0.  Up to 
  921.                   5 times faster than System.Insert.
  922.    Rating         31,900 str/sec
  923.    See also       StrCat, StrCopy
  924.    Example        Try the following examples:
  925.  
  926.                     S := 'Hello friends';
  927.                     J := 'Jim';
  928.                     Index := 7;                  {    123456789012345678 }
  929.                     StrIns (S,'my ',Index,255);  { S='Hello my friends'  }
  930.  
  931.                   Since StrIns lets you control MaxLen, the following line of 
  932.                   code:
  933.  
  934.                     StrIns (S,J,Index,pred(Index)+length(J));
  935.  
  936.                   Is the same as the following two lines:
  937.  
  938.  
  939.  
  940.    Chapter 2, Procedures and Functions                                 Page 16
  941.    STRG Utilities                               Reference Guide, Version 6.1a
  942.  
  943.  
  944.                     StrCut (S,pred(Index));   {    123456789 }
  945.                     StrCat (S,J,255);         { S='Hello Jim' }
  946.  
  947.    ---------------------------------------------------------------------------
  948.    StrJ* function                                                         Strg
  949.    ---------------------------------------------------------------------------
  950.    Function       Left, center, or right justifies a string in a field of 
  951.                   spaces.
  952.    Declaration    StrJC  (S: string; Field: byte)   { Justify center }
  953.                   StrJL  (S: string; Field: byte)   { Justify left   }
  954.                   StrJR  (S: string; Field: byte)   { Justify right  }
  955.    Result type    string
  956.    Remarks        If the field is smaller than the source string, the string 
  957.                   is simply returned unaltered.  These routines save from 
  958.                   recopying the string in the stack making it faster.
  959.    Rating         17,500 str/sec
  960.    See also       ChrPad*, StrOvr
  961.    Example        Try the following examples:
  962.  
  963.                     S := StrJC ('test',7);   { S=' test  ' }
  964.                     S := StrJL ('test',7);   { S='test   ' }
  965.                     S := StrJR ('test',7);   { S='   test' }
  966.  
  967.    ---------------------------------------------------------------------------
  968.    StrLwr procedure                                                       Strg
  969.    ---------------------------------------------------------------------------
  970.    Function       Converts strings to lower case.
  971.    Declaration    StrLwr (VAR S: string)
  972.    Remarks        The operation works on the entire string.
  973.    Rating         8,900 str/sec
  974.    See also       ChrReplI, LoCase, StrUpr, UpCase
  975.  
  976.    ---------------------------------------------------------------------------
  977.    StrMemb procedure                                                      Strg
  978.    ---------------------------------------------------------------------------
  979.    Function       Reduces a string to its membership in ascending order.
  980.    Declaration    StrMemb (VAR Dest: string; S: string)
  981.    Remarks        Membership is the list of characters that occur in a string.  
  982.                   Only one character is listed in the destination string for 
  983.                   any number of the same character in the source string.  
  984.                   Source and destination may be the same.  This is useful when 
  985.                   repeated scans are used on the same string for speed.
  986.    Rating         4,500 str/sec
  987.    See also       Is*, StrBrk, StrSort, StrSpn
  988.    Example        Try the following example:
  989.  
  990.                     var
  991.                       S1,S2: string;
  992.                     begin
  993.                       S1 := 'Eagle Performance Software 321';
  994.                       StrMemb (S2,S1);     { S2=' 123EPSacefglmnortw' }
  995.                     end.
  996.  
  997.  
  998.  
  999.  
  1000.    Chapter 2, Procedures and Functions                                 Page 17
  1001.    STRG Utilities                               Reference Guide, Version 6.1a
  1002.  
  1003.  
  1004.    ---------------------------------------------------------------------------
  1005.    StrMove procedure                                                      Strg
  1006.    ---------------------------------------------------------------------------
  1007.    Function       Moves a string to another location WITH the length byte.
  1008.    Declaration    StrMove (VAR Dest: string; S: string)
  1009.    Remarks        Up to 70% faster than using and assignment (":=").  Use when 
  1010.                   speed is essential.  Be sure Dest is large enough.
  1011.    Rating         53,400 str/sec
  1012.    See also       StrCat, StrCopy, StrOvr, StrPeek
  1013.    Example        Assign a string to another:
  1014.  
  1015.                     S1 := 'Now is the time';
  1016.                     StrMove (S2,S1);       { S2='Now is the time' }  
  1017.  
  1018.    ---------------------------------------------------------------------------
  1019.    StrOvr procedure                                                       Strg
  1020.    ---------------------------------------------------------------------------
  1021.    Function       Overwrites a string at a given index.
  1022.    Declaration    StrOvr (VAR Dest: string; S: string; Index: byte)
  1023.    Remarks        The length of the original string is increased if the 
  1024.                   substring makes it longer.  Any gap between the two 
  1025.                   strings is filled with spaces.  This is a move-type 
  1026.                   procedure, so be sure the destination is large enough.  
  1027.                   However, resulting strings are truncated at 255.
  1028.    Suggestions    This is a popular routine.  Use it when strings need to be 
  1029.                   aligned for formatting or displayed in columns.
  1030.    Rating         44,100 str/sec
  1031.    See also       Copy, StrCat, StrCopy, StrJ*, StrMove, StrPoke
  1032.    Example        Try the following examples:
  1033.  
  1034.                     S := 'Hello world';
  1035.                     StrOvr (S,'friends',7);   { S='Hello friends' }
  1036.                     T := 'First';             {    123456789012345678  }
  1037.                     StrOvr (T,'MI'  , 9);     { T='First   MI'         }
  1038.                     StrOvr (T,'Last',15);     { T='First   MI    Last' }
  1039.  
  1040.    ---------------------------------------------------------------------------
  1041.    StrPeek procedure                                                      Strg
  1042.    ---------------------------------------------------------------------------
  1043.    Function       Grabs an array in memory and converts it to a string.
  1044.    Declaration    StrPeek (VAR Dest: string; VAR Source; Count: byte)
  1045.    Remarks        Takes an array in memory at Source and converts it to a 
  1046.                   string at Dest.  Dest[0] cannot overlap Source.  This allows 
  1047.                   arrays to be handled as strings.
  1048.    Rating         42,100 str/sec
  1049.    See also       StrMove, StrPoke
  1050.    Example        Try the following example:
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.    Chapter 2, Procedures and Functions                                 Page 18
  1061.    STRG Utilities                               Reference Guide, Version 6.1a
  1062.  
  1063.  
  1064.                     const                      { 12345678901234567890123 }
  1065.                       A: array[1..23] of char = 'Eagle Performance, Inc.';
  1066.                     var
  1067.                       S: string;
  1068.                     begin
  1069.                       StrPeek (S,A[7],11);   { S='Performance' }
  1070.                     end.
  1071.  
  1072.    ---------------------------------------------------------------------------
  1073.    StrPoke procedure                                                      Strg
  1074.    ---------------------------------------------------------------------------
  1075.    Function       Pokes the characters of a string into memory.
  1076.    Declaration    StrPoke (VAR Dest; S: string)
  1077.    Remarks        Pokes the characters of S as an array into memory NOT 
  1078.                   including the length byte.  This allows strings to be 
  1079.                   handled as arrays.  Dest[0] cannot overlap S.
  1080.    Rating         43,600 str/sec
  1081.    See also       StrOvr, StrPeek
  1082.    Example        Try the following example:
  1083.  
  1084.                     const                      { 12345678901234567890123 }
  1085.                       A: array[1..23] of char = 'Eagle            , Inc.';
  1086.                       S: string = 'Performance';
  1087.                     begin                      { 12345678901234567890123 }
  1088.                       StrPoke (A[7],S);     { A='Eagle Performance, Inc.' }
  1089.                     end.
  1090.  
  1091.    ---------------------------------------------------------------------------
  1092.    StrPos* function                                                       Strg
  1093.    ---------------------------------------------------------------------------
  1094.    Function       Finds the position of a given string with match/ignore case.
  1095.    Declaration    StrPosL  (S,Find: string; Nth: byte)
  1096.                   StrPosLI (S,Find: string; Nth: byte)
  1097.                   StrPosR  (S,Find: string; Nth: byte)
  1098.                   StrPosRI (S,Find: string; Nth: byte)
  1099.                   StrPosX  (S,Find: string; indeX: byte)
  1100.                   StrPosXI (S,Find: string; indeX: byte)
  1101.    Result type    byte
  1102.    Remarks        Using suffixes, -L routine searches from the left while the 
  1103.                   -R searches from the right for the Nth occurrence.  The -X 
  1104.                   routine starts at the given index and searches right for the 
  1105.                   first occurrence.  These routines match case, while those 
  1106.                   with the added -I suffix will Ignore case.
  1107.    Rating         StrPos?  1-char:  23,900 str/sec
  1108.                   StrPos?  5-char:  18,200 str/sec
  1109.                   StrPos?I 1-char:   6,800 str/sec
  1110.                   StrPos?I 5-char:   5,900 str/sec
  1111.    See also       ChrPos*, StrBrk
  1112.  
  1113.    ---------------------------------------------------------------------------
  1114.    StrQty* function                                                       Strg
  1115.    ---------------------------------------------------------------------------
  1116.    Function       Counts the occurrences of a given substring in 
  1117.                   a string with match/ignore case. 
  1118.  
  1119.  
  1120.    Chapter 2, Procedures and Functions                                 Page 19
  1121.    STRG Utilities                               Reference Guide, Version 6.1a
  1122.  
  1123.  
  1124.    Declaration    StrQty  (S,Find: string)
  1125.                   StrQtyI (S,Find: string)
  1126.    Result type    byte
  1127.    Remarks        StrQty matches case while StrQtyI ignores case.
  1128.    Rating         StrQty  1-char:  23,900 str/sec
  1129.                   StrQty  5-char:  18,200 str/sec
  1130.                   StrQtyI 1-char:   6,800 str/sec
  1131.                   StrQtyI 5-char:   5,900 str/sec
  1132.    See also       ChrQty*, WrdQty
  1133.  
  1134.    ---------------------------------------------------------------------------
  1135.    StrRepl* procedure                                                     Strg
  1136.    ---------------------------------------------------------------------------
  1137.    Function       Finds and replaces a substring from a given index for Qty 
  1138.                   number of replacements with match/ignore case. 
  1139.    Declaration    StrRepl  (VAR S: string; Find,Repl: char; 
  1140.                             Index,Qty,MaxLen: byte)
  1141.                   StrReplI (VAR S: string; Find,Repl: char;
  1142.                             Index,Qty,MaxLen: byte)
  1143.    Remarks        The operation starts from Index and goes to the right.  It 
  1144.                   will stop if the index is beyond the end of string or it has 
  1145.                   replaced as many as it can.  StrRepl matches case while 
  1146.                   StrReplI ignores case.
  1147.                     The global variable ReplToDo is the result of Qty less the 
  1148.                   number of replacements that were done on the string.
  1149.                     MaxLen is used for the special case when the length of 
  1150.                   Repl is greater than Find.  The routine will replace as many 
  1151.                   as it can.  If one more replacement would cause the string 
  1152.                   length to be greater than MaxLen, the routine will stop at 
  1153.                   that find and report the index as ReplIndex and will set 
  1154.                   ReplOverFlow=true.  Otherwise, ReplIndex=0 and ReplOverFlow 
  1155.                   is false.
  1156.    Rating         StrRepl:  8,800 str/sec
  1157.                   StrReplI: 4,600 str/sec
  1158.    See also       ChrDel*, ChrRepl*
  1159.    Example        Try the following example:
  1160.  
  1161.                     var
  1162.                       S: string;
  1163.                     begin
  1164.                           { 1234567890123456789012345678901234 }
  1165.                       S := 'Fast TEST String, FAST test string';
  1166.                       StrReplI (S,'st','---',1,255,38);
  1167.                     end.
  1168.  
  1169.                   The results will be ReplOverFlow=true, ReplIndex=30, and 
  1170.                   ReplToDo=251 with S as follows:
  1171.  
  1172.                           { 12345678901234567890123456789012345678 }
  1173.                       S := 'Fa--- TE--- ---ring, FA--- test String';
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.    Chapter 2, Procedures and Functions                                 Page 20
  1181.    STRG Utilities                               Reference Guide, Version 6.1a
  1182.  
  1183.  
  1184.    ---------------------------------------------------------------------------
  1185.    StrReTab procedure                                                     Strg
  1186.    ---------------------------------------------------------------------------
  1187.    Function       Reduces spaces to tabs.
  1188.    Declaration    StrReTab (VAR Dest: string; S: string; TabSpaces: byte)
  1189.    Remarks        This routine reduces spaces with tabs given the tab spacing.  
  1190.                   Embedded tabs are accounted for.  Tab spacing is a minimum 
  1191.                   of one and zero values are forced to 1.  Position 1 is 
  1192.                   considered column 1.  Source and Dest can be the same 
  1193.                   address.
  1194.    Rating         6,000 str/sec
  1195.    See also       StrDeTab
  1196.    Example        Reduce spaces in the following string:
  1197.  
  1198.                         { 1234567890123456789012 }
  1199.                     S := '        Col 9   Col 17';
  1200.                     StrDeTab (S,S,8);         { S=#9'Col 9'#9'Col 17' }
  1201.  
  1202.    ---------------------------------------------------------------------------
  1203.    StrRev procedure                                                       Strg
  1204.    ---------------------------------------------------------------------------
  1205.    Function       Reverses the order of the characters in a string.
  1206.    Declaration    StrRev (VAR S: string)
  1207.    Rating         16,600 str/sec
  1208.    See also       StrEnum, StrSort
  1209.    Example        Try the following:
  1210.  
  1211.                     S := 'abcdefg';
  1212.                     StrRev (S);      { S='gfedcba' }
  1213.  
  1214.    ---------------------------------------------------------------------------
  1215.    StrRoll procedure                                                      Strg
  1216.    ---------------------------------------------------------------------------
  1217.    Function       Rolls the characters in a string forward or backward.
  1218.    Declaration    StrRoll (VAR S: string; Count: integer)
  1219.    Remarks        A forward roll moves characters from right to left and 
  1220.                   appends the rolled out characters on the right end.  A 
  1221.                   backward roll (a negative value) does the reverse.  If Count 
  1222.                   is greater than S[0], the Count is adjusted by mod.
  1223.    Rating         27,800 str/sec
  1224.    See also       StrRev, StrSort
  1225.    Example        Try the following:
  1226.  
  1227.                     S1 := '1234567890';  S2:=S1;
  1228.                     StrRoll (S1,2);    { S1='3456789012' }
  1229.                     StrRoll (S2,-2);   { S2='9012345678' }
  1230.  
  1231.    ---------------------------------------------------------------------------
  1232.    StrSort procedure                                                      Strg
  1233.    ---------------------------------------------------------------------------
  1234.    Function       Operates on a string by sorting it in ascending order.
  1235.    Declaration    StrSort (VAR S: string)
  1236.    Remarks        Two algorithms are used for this routine for speed.  For 
  1237.                   strings up to 22 chars long, the classic Quick Sort is used.  
  1238.  
  1239.  
  1240.    Chapter 2, Procedures and Functions                                 Page 21
  1241.    STRG Utilities                               Reference Guide, Version 6.1a
  1242.  
  1243.  
  1244.                   After 22 chars, the Tally Sort is used which is up to 10 
  1245.                   times faster than Quick Sort, because the Tally Sort does it 
  1246.                   in only two passes.
  1247.    Rating         3,600 str/sec
  1248.    See also       StrEnum, StrMemb, StrRev
  1249.    Suggestions    This routine is so efficient, you can even use it to sort 
  1250.                   any byte arrays by using an absolute variable at the address 
  1251.                   you want to sort or you can use StrPeek/StrPoke for arrays 
  1252.                   up to 255 bytes.
  1253.    Example        Try the following:
  1254.  
  1255.                     S := 'fgb1edca';
  1256.                     StrSort (S);      { S='1abcdefg' }
  1257.  
  1258.    ---------------------------------------------------------------------------
  1259.    StrSpn function                                                        Strg
  1260.    ---------------------------------------------------------------------------
  1261.    Function       Counts the number of consecutive characters that are all 
  1262.                   members of a group of chars.
  1263.    Declaration    StrSpn (S,Members: string; Index: byte)
  1264.    Result type    byte
  1265.    Remarks        The function scans the string S starting at Index and scans 
  1266.                   RIGHT.  Members is any group of characters.  As long as the 
  1267.                   scanned character is in Members, it will continue to scan 
  1268.                   for the next one until it finds a non-member of Members.  
  1269.                   The result is the span (Spn) of the substring that are all 
  1270.                   members.  This routine is usually used to parse a string.  
  1271.                   For greater speed, place the most commonly used members 
  1272.                   early in Members.
  1273.    Rating         1-char Members: 23,600 str/sec
  1274.                   5-char Members:  3,600 str/sec
  1275.    See also       StrBrk, StrMemb, Wrd*, WrdParse, WrdToken
  1276.    Example        Find the length of the number in string S:
  1277.  
  1278.                     var 
  1279.                       S,Numbers: string;
  1280.                       Size: byte;
  1281.                     begin
  1282.                       S := 'Balance $24,567.00 in credits.';
  1283.                       StrEnum (Numbers,'0','9');
  1284.                       StrCat (Numbers,'+-.,',255);
  1285.                       Size := StrSpn (S,Numbers,10); { Size=9 }
  1286.                     end.
  1287.  
  1288.    ---------------------------------------------------------------------------
  1289.    StrUpr procedure                                                       Strg
  1290.    ---------------------------------------------------------------------------
  1291.    Function       Converts strings to upper case.
  1292.    Declaration    StrUpr (VAR S: string)
  1293.    Remarks        The operation works on the entire string.
  1294.    Rating         8,900 str/sec
  1295.    See also       ChrReplI, LoCase, StrLwr, UpCase
  1296.  
  1297.  
  1298.  
  1299.  
  1300.    Chapter 2, Procedures and Functions                                 Page 22
  1301.    STRG Utilities                               Reference Guide, Version 6.1a
  1302.  
  1303.  
  1304.    ---------------------------------------------------------------------------
  1305.    UpCase function                                                        Strg
  1306.    ---------------------------------------------------------------------------
  1307.    Function       Converts characters to upper case.
  1308.    Declaration    UpCase (C: char)
  1309.    Result type    char
  1310.    Remarks        About 3 times faster than System.UpCase producing identical 
  1311.                   results.
  1312.    See also       ChrReplI, LoCase, StrLwr, StrUpr
  1313.  
  1314.    ---------------------------------------------------------------------------
  1315.    ValBin function                                                        Strg
  1316.    ---------------------------------------------------------------------------
  1317.    Function       Converts binary strings to longint.
  1318.    Declaration    ValBin (S: string; VAR Code: integer)
  1319.    Result type    longint (but smaller types are permissible)
  1320.    Remarks        ValBin has these superior features:
  1321.  
  1322.                     - Leading spaces are permitted but not trailing ones.
  1323.                     - Leading zeros are also permitted.
  1324.                     - A non-zero error code points to the invalid character in 
  1325.                       the string.
  1326.                     - Numbers larger than $FFFFFFFF produce an error.
  1327.                     - ValBin salvages a value even if there is an error!
  1328.                     - Routine is more flexible as a function rather than being 
  1329.                       similar to the Val procedure which is compiler dependent 
  1330.                       on the number type.
  1331.  
  1332.    Rating         25,500 str/sec
  1333.    See also       StrBin, StrHex, ValHex
  1334.    Example        In the last example, Code=9.  The others set Code=0.
  1335.  
  1336.                     LongInt1 := ValBin ('001100100',Code);  { LontInt1=100 }
  1337.                     LongInt2 := ValBin ('111110100',Code);  { LongInt2=500 }
  1338.                     LongInt3 := ValBin ('  101101b',Code);  { LongInt3=45  }
  1339.  
  1340.    ---------------------------------------------------------------------------
  1341.    ValHex function                                                        Strg
  1342.    ---------------------------------------------------------------------------
  1343.    Function       Converts hex strings to longint.
  1344.    Declaration    ValHex (S: string; VAR Code: integer)
  1345.    Result type    longint (but smaller types are permissible)
  1346.    Remarks        ValHex has these superior features:
  1347.  
  1348.                     - Leading spaces are permitted but not trailing ones.
  1349.                     - Leading zeros are also permitted.
  1350.                     - The leading '$' is optional!
  1351.                     - A non-zero error code points to the invalid character in 
  1352.                       the string.
  1353.                     - Numbers larger than $FFFFFFFF produce an error.
  1354.                     - ValHex salvages a value even if there is an error!
  1355.                     - Twice as fast as Val and uses much less code.
  1356.                     - Routine is more flexible as a function rather than the 
  1357.                       Val procedure which is compiler dependent on the number 
  1358.  
  1359.  
  1360.    Chapter 2, Procedures and Functions                                 Page 23
  1361.    STRG Utilities                               Reference Guide, Version 6.1a
  1362.  
  1363.  
  1364.                       type.
  1365.  
  1366.    Rating         27,200 str/sec
  1367.    See also       StrBin, StrHex, ValBin
  1368.    Example        In the last example, Code=5.  The others set Code=0.
  1369.  
  1370.  
  1371.                     LongInt1 := ValHex (' 0064',Code);  { LongInt1=100 }
  1372.                     LongInt2 := ValHex (' $1f4',Code);  { LongInt1=500 }
  1373.                     LongInt3 := ValHex ('  2Dh',Code);  { LongInt1=45  }
  1374.  
  1375.    ---------------------------------------------------------------------------
  1376.    Wrd* procedure                                                         Strg
  1377.    ---------------------------------------------------------------------------
  1378.    Function       Parses words separated by spaces.
  1379.    Declaration    WrdL  (VAR Dest: string; S: string; Nth: byte)
  1380.                   WrdR  (VAR Dest: string; S: string; Nth: byte)
  1381.                   WrdLX (VAR Dest: string; S: string; indeX: byte)
  1382.                   WrdRX (VAR Dest: string; S: string; indeX: byte)
  1383.    Remarks        A word at the beginning or end of a string is considered a 
  1384.                   word even though it does not have spaces on both ends.  The 
  1385.                   procedures apply as follows:
  1386.  
  1387.                     WrdL  - parses Nth word from the Left
  1388.                     WrdR  - parses Nth word from the Right
  1389.                     WrdLX - parses first word from Left starting at indeX.
  1390.                     WrdRX - parses first word from Right starting at indeX.
  1391.  
  1392.                   WrdLX and WrdRX parses the first word with its first letter 
  1393.                   found in the direction of search even if it starts at indeX.
  1394.    Rating         Wrd?:  16,400 str/sec
  1395.                   Wrd?X: 25,100 str/sec
  1396.    See also       StrBrk, StrSpn, WrdPos*, WrdParse, WrdToken
  1397.    Example        Try the following parsing:
  1398.  
  1399.                     var S,W1,W2,W3,W4: string;
  1400.                     begin
  1401.                       S := 'Eagle Performance Software Products';     
  1402.                       WrdL  (W1,S,2);      { W1='Performance'}
  1403.                       WrdR  (W2,S,2);      { W2='Software'   }
  1404.                       WrdLX (W3,S,2);      { W3='Performance'}
  1405.                       WrdRX (W4,S,255);    { W1='Products'   }
  1406.                     end.
  1407.  
  1408.    ---------------------------------------------------------------------------
  1409.    WrdParse procedure                                                     Strg
  1410.    ---------------------------------------------------------------------------
  1411.    Function       Generic parsing routine.
  1412.    Declaration    WrdParse (VAR Dest: string; S,Delims: string; 
  1413.                             VAR Index: byte)
  1414.    Remarks        Delims is a group of characters considered delimiters.  
  1415.                   (Place the most used delimiters early in the string for 
  1416.                   faster performance.)  WrdParse extracts the next delimited 
  1417.                   word RIGHT from the given Index and does not search 
  1418.  
  1419.  
  1420.    Chapter 2, Procedures and Functions                                 Page 24
  1421.    STRG Utilities                               Reference Guide, Version 6.1a
  1422.  
  1423.  
  1424.                   backwards.  WrdParse adjusts Index so it marks where to 
  1425.                   start the next parse on the next call.  Routine has fully 
  1426.                   scanned when resulting indeX is set to zero.  Different from 
  1427.                   WrdToken, nulls are significant; i.e., two delimiters in 
  1428.                   sequence is considered a null parse.  So, if a delimiter is 
  1429.                   at the end of a string, the final parse returned is null.
  1430.    Rating         1-char Delims: 28,500 str/sec
  1431.                   5-char Delims:  6,500 str/sec
  1432.    See also       StrBrk, StrSpn, Wrd*, WrdPos*, WrdToken
  1433.    Example        Parse the following string S into the string array:
  1434.  
  1435.                     uses strg;
  1436.                     var
  1437.                       A: array[0..4] of string;
  1438.                       i,j,Index: byte;
  1439.                       D,S: string;
  1440.                     begin
  1441.                       S := 'Faster, yet better';
  1442.                       D := ' ,.';       { These are the delimiters. }
  1443.                       i := 0;           { First parse will be in Sarray[0] }
  1444.                       Index := 1;       { Start at first character }
  1445.                       while Index<>0 do
  1446.                         begin
  1447.                           WrdParse (A[i],S,D,Index);
  1448.                           inc (i);
  1449.                         end;
  1450.                     end.
  1451.  
  1452.                   Program will end with i=4 which is the number of parses 
  1453.                   found.  The results are A[0]='Faster', A[1]='', A[2]='yet', 
  1454.                   and A[3]='better'.  A[1] is null because a null string was 
  1455.                   parsed between the comma and space which is useful for 
  1456.                   parsing command line entries that are null.
  1457.  
  1458.    ---------------------------------------------------------------------------
  1459.    WrdPos* function                                                       Strg
  1460.    ---------------------------------------------------------------------------
  1461.    Function       Returns position of word delimited by spaces.
  1462.    Declaration    WrdPosL  (S: string; Nth: byte)
  1463.                   WrdPosR  (S: string; Nth: byte)
  1464.                   WrdPosLX (S: string; indeX: byte)
  1465.                   WrdPosRX (S: string; indeX: byte)
  1466.    Result type    byte
  1467.    Remarks        A word at the beginning or end of a string is considered a 
  1468.                   word even though it does not have spaces on both ends.  The 
  1469.                   procedures apply as follows:
  1470.  
  1471.                     WrdPosL  - find Nth word from the Left
  1472.                     WrdPosR  - find Nth word from the Right
  1473.                     WrdPosLX - find first word from Left starting at indeX.
  1474.                     WrdPosRX - find first word from Right starting at indeX.
  1475.  
  1476.                   If the index is not located on the first letter of a word, 
  1477.                   WrdPosLX and WrdPosRX will continue scanning for the next 
  1478.  
  1479.  
  1480.    Chapter 2, Procedures and Functions                                 Page 25
  1481.    STRG Utilities                               Reference Guide, Version 6.1a
  1482.  
  1483.  
  1484.                   word.
  1485.    Rating         WrdPos?:  17,700 str/sec
  1486.                   WrdPos?X: 26,400 str/sec
  1487.    See also       StrBrk, StrSpn, Wrd*, WrdParse, WrdToken
  1488.    Example        Try the following examples:
  1489.  
  1490.                         { 12345678901234567890123456789012345678 }
  1491.                     S := 'Now is the time for all good programs.';
  1492.                     MyByte := WrdPosR  (S,1);   { MyByte=30 }
  1493.                     MyByte := WrdPosL  (S,3);   { MyByte= 8 }
  1494.                     MyByte := WrdPosLX (S,9);   { MyByte=12 }
  1495.                     MyByte := WrdPosRX (S,9);   { MyByte= 8 }
  1496.  
  1497.    ---------------------------------------------------------------------------
  1498.    WrdQty function                                                        Strg
  1499.    ---------------------------------------------------------------------------
  1500.    Function       Counts the number of words in a string delimited by spaces.
  1501.    Declaration    WrdQty (S: string)
  1502.    Result type    byte
  1503.    Remarks        A word at the beginning or end of a string is considered a 
  1504.                   word even though it does not have spaces on both ends.
  1505.    Rating         18,400 str/sec
  1506.    See also       ChrQty*, StrQty*
  1507.    Example        Try the following example:
  1508.  
  1509.                     S := 'Now is the time for all good programs.';
  1510.                     MyByte := WrdQty (S);    { MyByte=8 }
  1511.  
  1512.    ---------------------------------------------------------------------------
  1513.    WrdToken procedure                                                     Strg
  1514.    ---------------------------------------------------------------------------
  1515.    Function       Generic token parsing routine.
  1516.    Declaration    WrdToken (VAR Dest: string; S,Delims: string; 
  1517.                             VAR indeX: byte)
  1518.    Remarks        Delims is a group of characters considered delimiters.  
  1519.                   (Place the most used delimiters early in the string for 
  1520.                   faster performance.)  WrdToken extracts the next delimited 
  1521.                   word RIGHT from the given indeX and does not search 
  1522.                   backwards.  WrdToken adjusts indeX so it marks where to 
  1523.                   start the next parse on the next call.  Routine has fully 
  1524.                   scanned when resulting indeX is set to zero.  Different from 
  1525.                   WrdParse, nulls are NOT significant; i.e., all delimiters 
  1526.                   are passed over until the next token is found.  But, if a 
  1527.                   delimiter is at the end of a string, the final token 
  1528.                   returned is still null.
  1529.    Rating         1-char Delims: 28,500 str/sec
  1530.                   5-char Delims:  6,500 str/sec
  1531.    See also       StrBrk, StrSpn, Wrd*, WrdPos*, WrdParse
  1532.    Example        Parse the following S into the string array:
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.    Chapter 2, Procedures and Functions                                 Page 26
  1541.    STRG Utilities                               Reference Guide, Version 6.1a
  1542.  
  1543.  
  1544.                     uses strg;
  1545.                     var
  1546.                       A: array[0..4] of string;
  1547.                       i,j,Index: byte;
  1548.                       D,S: string;
  1549.                     begin
  1550.                       S := 'Faster, yet better';
  1551.                       D := ' ,.';       { These are the delimiters. }
  1552.                       i := 0;           { First parse will be in A[0] }
  1553.                       Index := 1;       { Start at first character }
  1554.                       while Index<>0 do
  1555.                         begin
  1556.                           WrdToken (A[i],S,D,Index);
  1557.                           inc (i);
  1558.                         end;
  1559.                     end.
  1560.  
  1561.                   Program will end with i=3 which is the number of tokens 
  1562.                   found.  The results are A[0]='Faster', A[1]='yet', and 
  1563.                   A[2]='better'.
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595.  
  1596.  
  1597.  
  1598.  
  1599.  
  1600.    Chapter 2, Procedures and Functions                                 Page 27
  1601.    STRG Utilities                               Reference Guide, Version 6.1a
  1602.  
  1603.  
  1604.    3.  V A R I A B L E S
  1605.  
  1606.    There are only a few variables to consider in the STRG unit.  Some can be 
  1607.    accessed for global use and just one is local.
  1608.  
  1609.  
  1610.    GLOBAL           
  1611.  
  1612.    Global Variables - These variables can be used to assist your programs more 
  1613.    efficiently:
  1614.  
  1615.      Variable      Description
  1616.      ------------  -----------------------------------------------------------
  1617.      AscDestPtr    (Type: Pointer) After AscStr is executed, this pointer 
  1618.                    points to the next ASCIIZ destination after the end-of-
  1619.                    string null.  This is very useful for sequential 
  1620.                    conversions to save space with ASCIIZ strings.
  1621.  
  1622.      AscSrcPtr     (Type: Pointer) After StrAsc is executed, this pointer 
  1623.                    points to the next ASCIIZ source after the end-of-string 
  1624.                    null or the next valid character if the conversion is 
  1625.                    limited by MaxLen.  This is very useful for sequential 
  1626.                    conversions from contiguous ASCIIZ strings.
  1627.  
  1628.      CmpIndex1     (Type: Integer)  After strings are compared with StrCmp*, 
  1629.                    the index of difference for S1 is saved in this variable.  
  1630.                    The integer type is used in lieu of byte for the case of 
  1631.                    difference at column 256 (Index1+MaxLen>255).  If you do 
  1632.                    not use strings out to S1[255], then it is permissible to 
  1633.                    use byte assignments to this variable.
  1634.  
  1635.      CmpIndex2     (Type: Integer)  Same as CmpIndex1 except it applies to S2.
  1636.  
  1637.      LnDestPtr     (Type: Pointer) After LnStr is executed, this pointer 
  1638.                    points to the next ASCII text file destination after the 
  1639.                    end-of-string CR/LF.  This is very useful for sequential 
  1640.                    conversions to an ASCII text file for a block write.
  1641.  
  1642.      LnSrcPtr      (Type: Pointer) After StrLn is executed, this pointer 
  1643.                    points to the next ASCII text file source after the end-of-
  1644.                    string CR/LF, CR, or the next valid character if the 
  1645.                    conversion is limited by MaxLen.  This is very useful for 
  1646.                    sequential conversions from a block read of an ASCII text 
  1647.                    file.
  1648.  
  1649.      ReplIndex     (Type: Byte)  After using StrRepl* and there is an 
  1650.                    overflow, this variable provides the index where the 
  1651.                    operation was halted. 
  1652.  
  1653.      ReplOverFlow  (Type: Boolean)  After using StrRepl* when the replacement 
  1654.                    string is longer than the find string and the resulting 
  1655.                    string would be longer than MaxLen permits, this value is 
  1656.                    set to TRUE.  This means the operation went as far as it 
  1657.                    could go before overflowing the length.
  1658.  
  1659.  
  1660.    Chapter 3, Variables                                                Page 28
  1661.    STRG Utilities                               Reference Guide, Version 6.1a
  1662.  
  1663.  
  1664.  
  1665.      ReplToDo      (Type: Byte)  After using StrRepl*, this variable indicates 
  1666.                    how many replacements are still needed to fulfill the 
  1667.                    original request.  If it is zero, then all replacements 
  1668.                    were done.
  1669.  
  1670.  
  1671.    LOCAL
  1672.  
  1673.    Local Constant - There is only one local constant to STRG:
  1674.  
  1675.      Constant      Description
  1676.      ------------  -----------------------------------------------------------
  1677.      ChrClass      (Type: array of char)  Several of the more complicated Is* 
  1678.                    functions use this 128 char array to quickly classify 
  1679.                    characters by testing individual bits in the array.  
  1680.                    Simpler Is* functions do not use this array and it is 
  1681.                    optimized out of the program.
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.    Chapter 3, Variables                                                Page 29
  1721.    STRG Utilities                               Reference Guide, Version 6.1a
  1722.  
  1723.  
  1724.    4.  A C C E S S I B L E   M E M O R Y 
  1725.  
  1726.    Many of the routines in STRG use 16-bit transfers to increase string 
  1727.    processing.  As as you program to normally to RAM, these routines will work 
  1728.    fine.  Just remember that certain hardware other than RAM can have 
  1729.    limitations.  The only one of which we are aware is trying to use these 
  1730.    routines for direct manipulation of the EGA/VGA bit plane memory for video 
  1731.    graphics, which would indeed be a bizarre application for these routines.
  1732.  
  1733.    For graphics programming, either stick to the BGI drivers, or use routines 
  1734.    that only have 8-bit transfers.  For more info on this limitation on video 
  1735.    hardware, check out page 114 of Richard Wilton's book "Programmer's Guide 
  1736.    to PC & PS/2 Video Systems".
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.    Chapter 4, Accessible Memory                                        Page 30
  1781.    STRG Utilities                               Reference Guide, Version 6.1a
  1782.  
  1783.  
  1784.    5.  Q U I C K   R E F E R E N C E
  1785.  
  1786.    For a quick reference for all of the declarations contained in this unit, 
  1787.    the following are all the routines listed in alphabetical order.
  1788.  
  1789.   procedure AscStr   (VAR AscDest; S: string);
  1790.   procedure ChrDel   (VAR S: string; Find: char);
  1791.   procedure ChrDelL  (VAR S: string; Find: char);
  1792.   procedure ChrDelR  (VAR S: string; Find: char);
  1793.   procedure ChrFill  (VAR S: string; Fill: char; Count: byte);
  1794.   procedure ChrPadC  (VAR S: string; Find: char; Field: byte);
  1795.   procedure ChrPadL  (VAR S: string; Find: char; Field: byte);
  1796.   procedure ChrPadR  (VAR S: string; Find: char; Field: byte);
  1797.   function  ChrPosL  (S: string; Find: char; Nth: byte):   byte;
  1798.   function  ChrPosLI (S: string; Find: char; Nth: byte):   byte;
  1799.   function  ChrPosR  (S: string; Find: char; Nth: byte):   byte;
  1800.   function  ChrPosRI (S: string; Find: char; Nth: byte):   byte;
  1801.   function  ChrPosX  (S: string; Find: char; indeX: byte): byte;
  1802.   function  ChrPosXI (S: string; Find: char; indeX: byte): byte;
  1803.   function  ChrQty   (S: string; Find: char): byte;
  1804.   function  ChrQtyI  (S: string; Find: char): byte;
  1805.   procedure ChrRepl  (VAR S: string; Find,Repl: char; Index,Qty: byte);
  1806.   procedure ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte);
  1807.   function  Copy     (    S: string; Index,Count: integer): string;
  1808.   procedure Delete   (VAR S: string; Index,Count: integer);
  1809.   function  IsAlNum  (C: char): boolean;
  1810.   function  IsAlpha  (C: char): boolean;
  1811.   function  IsASCII  (C: char): boolean;
  1812.   function  IsCntrl  (C: char): boolean;
  1813.   function  IsDigit  (C: char): boolean;
  1814.   function  IsDOS    (C: char): boolean;
  1815.   function  IsFile   (C: char): boolean;
  1816.   function  IsGraph  (C: char): boolean;
  1817.   function  IsLower  (C: char): boolean;
  1818.   function  IsPath   (C: char): boolean;
  1819.   function  IsPrint  (C: char): boolean;
  1820.   function  IsPunct  (C: char): boolean;
  1821.   function  IsReal   (C: char): boolean;
  1822.   function  IsSigned (C: char): boolean;
  1823.   function  IsSpace  (C: char): boolean;
  1824.   function  IsUpper  (C: char): boolean;
  1825.   function  IsXDigit (C: char): boolean;
  1826.   procedure LnStr    (VAR LnDest; S: string);
  1827.   function  LoCase   (C: char): char;
  1828.   function  Pos      (Find,S: string): byte;
  1829.   procedure StrAsc   (VAR Dest: string; VAR AscSrc; MaxLen: byte);
  1830.   function  StrBin   (Num: longint; Field: byte): string;
  1831.   function  StrBrk   (S,Breaks: string; Index: byte): byte;
  1832.   function  StrC     (C: comp): string;
  1833.   procedure StrCat   (VAR Dest: string; S: string; MaxLen: byte);
  1834.   procedure StrCatX  (VAR Dest: string; S: string; indeX,Count,MaxLen: byte);
  1835.   function  StrCF    (C: comp; Field: integer):          string;
  1836.   function  StrCFD   (C: comp; Field,Decimals: integer): string;
  1837.   function  StrCmp   (S1,S2: string; Index1,Index2,MaxLen: byte): shortint;
  1838.  
  1839.  
  1840.    Chapter 5, Quick Reference                                          Page 31
  1841.    STRG Utilities                               Reference Guide, Version 6.1a
  1842.  
  1843.  
  1844.   function  StrCmpI  (S1,S2: string; Index1,Index2,MaxLen: byte): shortint;
  1845.   procedure StrCopy  (VAR Dest: string; S: string; Index,Count: byte);
  1846.   procedure StrCut   (VAR S: string; MaxLen: byte);
  1847.   function  StrD     (D: double): string;
  1848.   procedure StrDeTab (VAR Dest: string; S: string; TabSpaces: byte);
  1849.   function  StrDF    (D: double; Field: integer):            string;
  1850.   function  StrDFD   (D: double; Field,Decimals: integer):   string;
  1851.   function  StrE     (E: extended):                          string;
  1852.   function  StrEF    (E: extended; Field: integer):          string;
  1853.   function  StrEFD   (E: extended; Field,Decimals: integer): string;
  1854.   procedure StrEnum  (VAR S: string; First,Last: char);
  1855.   procedure StrFill  (VAR S: string; Fill: string; Count,MaxLen: byte);
  1856.   function  StrHex   (Num: longint; Field: byte): string;
  1857.   procedure StrIns   (VAR Dest: string; S: string; DestIndex,MaxLen: byte);
  1858.   function  StrJC    (S: string; Field: byte): string;
  1859.   function  StrJL    (S: string; Field: byte): string;
  1860.   function  StrJR    (S: string; Field: byte): string;
  1861.   function  StrL     (L: longint):                 string;
  1862.   function  StrLF    (L: longint; Field: integer): string;
  1863.   procedure StrLn    (VAR Dest: string; VAR LnSrc; MaxLen: byte);
  1864.   procedure StrLwr   (VAR S: string);
  1865.   procedure StrMemb  (VAR Dest: string; S: string);
  1866.   procedure StrMove  (VAR Dest: string; S: string);
  1867.   procedure StrOvr   (VAR Dest: string; S: string; DestIndex: byte);
  1868.   procedure StrPeek  (VAR Dest: string; VAR Source; Count: byte);
  1869.   procedure StrPoke  (VAR Dest; S: string);
  1870.   function  StrPosL  (S,Find: string; Nth: byte):   byte;
  1871.   function  StrPosLI (S,Find: string; Nth: byte):   byte;
  1872.   function  StrPosR  (S,Find: string; Nth: byte):   byte;
  1873.   function  StrPosRI (S,Find: string; Nth: byte):   byte;
  1874.   function  StrPosX  (S,Find: string; indeX: byte): byte;
  1875.   function  StrPosXI (S,Find: string; indeX: byte): byte;
  1876.   function  StrQty   (S,Find: string):              byte;
  1877.   function  StrQtyI  (S,Find: string):              byte;
  1878.   function  StrR     (R: real): string;
  1879.   procedure StrRepl  (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte);
  1880.   procedure StrReplI (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte);
  1881.   procedure StrReTab (VAR Dest: string; S: string; TabSpaces: byte);
  1882.   procedure StrRev   (VAR S: string);
  1883.   function  StrRF    (R: real; Field: integer):          string;
  1884.   function  StrRFD   (R: real; Field,Decimals: integer): string;
  1885.   procedure StrRoll  (VAR S: string; Count: integer);
  1886.   function  StrS     (S: single):                          string;
  1887.   function  StrSF    (S: single; Field: integer):          string;
  1888.   function  StrSFD   (S: single; Field,Decimals: integer): string;
  1889.   procedure StrSort  (VAR S: string);
  1890.   function  StrSpn   (S,Members: string; Index: byte): byte;
  1891.   procedure StrUpr   (VAR S: string);
  1892.   function  UpCase   (C: char): char;
  1893.   function  ValBin   (S: string; VAR Code: integer): longint;
  1894.   function  ValHex   (S: string; VAR Code: integer): longint;
  1895.   procedure WrdL     (VAR Dest: string; S: string; Nth: byte);
  1896.   procedure WrdLX    (VAR Dest: string; S: string; indeX: byte);
  1897.   procedure WrdParse (VAR Dest: string; S,Delims: string; VAR Index: byte);
  1898.  
  1899.  
  1900.    Chapter 5, Quick Reference                                          Page 32
  1901.    STRG Utilities                               Reference Guide, Version 6.1a
  1902.  
  1903.  
  1904.   function  WrdPosL  (S: string; Nth: byte):   byte;
  1905.   function  WrdPosLX (S: string; indeX: byte): byte;
  1906.   function  WrdPosR  (S: string; Nth: byte):   byte;
  1907.   function  WrdPosRX (S: string; indeX: byte): byte;
  1908.   function  WrdQty   (S: string):              byte;
  1909.   procedure WrdR     (VAR Dest: string; S: string; Nth: byte);
  1910.   procedure WrdRX    (VAR Dest: string; S: string; indeX: byte);
  1911.   procedure WrdToken (VAR Dest: string; S,Delims: string; VAR Index: byte);
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.  
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.    Chapter 5, Quick Reference                                          Page 33
  1961.